<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
  
  <!-- Licensed under the Apache 2.0 License -->
  <link rel="stylesheet" type="text/css" href="_static/fonts/open-sans/stylesheet.css" />
  <!-- Licensed under the SIL Open Font License -->
  <link rel="stylesheet" type="text/css" href="_static/fonts/source-serif-pro/source-serif-pro.css" />
  <link rel="stylesheet" type="text/css" href="_static/css/bootstrap.min.css" />
  <link rel="stylesheet" type="text/css" href="_static/css/bootstrap-theme.min.css" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
    <title>Getting Started &#8212; ElasticHQ latest documentation</title>
    
    <link rel="stylesheet" href="_static/guzzle.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     'latest',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="ElasticHQ latest documentation" href="index.html" />
    <link rel="next" title="REST API" href="rest-api.html" />
    <link rel="prev" title="ElasticHQ Documentation" href="index.html" />
  
   

  </head>
  <body role="document">
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="http-routingtable.html" title="HTTP Routing Table"
             >routing table</a> |</li>
        <li class="right" >
          <a href="rest-api.html" title="REST API"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="index.html" title="ElasticHQ Documentation"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">ElasticHQ latest documentation</a> &#187;</li> 
      </ul>
    </div>
    <div class="container-wrapper">

      <div id="mobile-toggle">
        <a href="#"><span class="glyphicon glyphicon-align-justify" aria-hidden="true"></span></a>
      </div>
  <div id="left-column">
    <div class="sphinxsidebar"><a href="
    index.html" class="text-logo">ElasticHQ</a>
<div class="sidebar-block">
  <div class="sidebar-wrapper">
    <h2>Table Of Contents</h2>
  </div>
  <div class="sidebar-toc">
    
    
      <ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Getting Started</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#quick-start-guide">Quick-Start Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="#running-with-docker">Running with Docker</a></li>
<li class="toctree-l2"><a class="reference internal" href="#install-from-source">Install from Source</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#requirements">Requirements</a></li>
<li class="toctree-l3"><a class="reference internal" href="#install-elastichq">Install ElasticHQ</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pre-releases">Pre-Releases</a></li>
<li class="toctree-l3"><a class="reference internal" href="#openshift">OpenShift</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#initial-login">Initial Login</a></li>
<li class="toctree-l2"><a class="reference internal" href="#configuration">Configuration</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#command-line-parameters">Command line Parameters</a></li>
<li class="toctree-l3"><a class="reference internal" href="#environment-variables">Environment Variables</a></li>
<li class="toctree-l3"><a class="reference internal" href="#logging">Logging</a></li>
<li class="toctree-l3"><a class="reference internal" href="#connecting-with-ssl">Connecting with SSL</a></li>
<li class="toctree-l3"><a class="reference internal" href="#database">Database</a></li>
<li class="toctree-l3"><a class="reference internal" href="#external-configuration">External Configuration</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#upgrading">Upgrading</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#latest-version">Latest Version</a></li>
<li class="toctree-l3"><a class="reference internal" href="#upgrading-minor-and-patch-versions">Upgrading Minor and Patch versions</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#running-in-production">Running in Production</a></li>
<li class="toctree-l2"><a class="reference internal" href="#troubleshooting">Troubleshooting</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#diagnosing-connection-errors">Diagnosing connection errors</a></li>
<li class="toctree-l3"><a class="reference internal" href="#x-pack-integration">X-Pack Integration</a></li>
<li class="toctree-l3"><a class="reference internal" href="#viewing-logs">Viewing Logs</a></li>
<li class="toctree-l3"><a class="reference internal" href="#ssl-cert-not-working">SSL Cert not working</a></li>
<li class="toctree-l3"><a class="reference internal" href="#preserving-database-across-docker-container-restarts">Preserving Database across Docker container restarts</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#license">License</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="rest-api.html">REST API</a></li>
<li class="toctree-l1"><a class="reference internal" href="developer-guide.html">For Developers</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li>
</ul>

    
  </div>
</div>
<div class="sidebar-block">
  <div class="sidebar-wrapper">
    <div id="main-search">
      <form class="form-inline" action="search.html" method="GET" role="form">
        <div class="input-group">
          <input name="q" type="text" class="form-control" placeholder="Search...">
        </div>
        <input type="hidden" name="check_keywords" value="yes" />
        <input type="hidden" name="area" value="default" />
      </form>
    </div>
  </div>
</div>
      
    </div>
  </div>
        <div id="right-column">
          
          <div role="navigation" aria-label="breadcrumbs navigation">
            <ol class="breadcrumb">
              <li><a href="index.html">Docs</a></li>
              
              <li>Getting Started</li>
            </ol>
          </div>
          
          <div class="document clearer body">
            
  <div class="section" id="getting-started">
<h1>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#quick-start-guide" id="id4">Quick-Start Guide</a></li>
<li><a class="reference internal" href="#running-with-docker" id="id5">Running with Docker</a></li>
<li><a class="reference internal" href="#install-from-source" id="id6">Install from Source</a><ul>
<li><a class="reference internal" href="#requirements" id="id7">Requirements</a></li>
<li><a class="reference internal" href="#install-elastichq" id="id8">Install ElasticHQ</a></li>
<li><a class="reference internal" href="#pre-releases" id="id9">Pre-Releases</a></li>
<li><a class="reference internal" href="#openshift" id="id10">OpenShift</a></li>
</ul>
</li>
<li><a class="reference internal" href="#initial-login" id="id11">Initial Login</a></li>
<li><a class="reference internal" href="#configuration" id="id12">Configuration</a><ul>
<li><a class="reference internal" href="#command-line-parameters" id="id13">Command line Parameters</a></li>
<li><a class="reference internal" href="#environment-variables" id="id14">Environment Variables</a></li>
<li><a class="reference internal" href="#logging" id="id15">Logging</a></li>
<li><a class="reference internal" href="#connecting-with-ssl" id="id16">Connecting with SSL</a></li>
<li><a class="reference internal" href="#database" id="id17">Database</a></li>
<li><a class="reference internal" href="#external-configuration" id="id18">External Configuration</a></li>
</ul>
</li>
<li><a class="reference internal" href="#upgrading" id="id19">Upgrading</a><ul>
<li><a class="reference internal" href="#latest-version" id="id20">Latest Version</a></li>
<li><a class="reference internal" href="#upgrading-minor-and-patch-versions" id="id21">Upgrading Minor and Patch versions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#running-in-production" id="id22">Running in Production</a></li>
<li><a class="reference internal" href="#troubleshooting" id="id23">Troubleshooting</a><ul>
<li><a class="reference internal" href="#diagnosing-connection-errors" id="id24">Diagnosing connection errors</a></li>
<li><a class="reference internal" href="#x-pack-integration" id="id25">X-Pack Integration</a></li>
<li><a class="reference internal" href="#viewing-logs" id="id26">Viewing Logs</a></li>
<li><a class="reference internal" href="#ssl-cert-not-working" id="id27">SSL Cert not working</a></li>
<li><a class="reference internal" href="#preserving-database-across-docker-container-restarts" id="id28">Preserving Database across Docker container restarts</a></li>
</ul>
</li>
<li><a class="reference internal" href="#license" id="id29">License</a></li>
</ul>
</div>
<div class="section" id="quick-start-guide">
<h2><a class="toc-backref" href="#id4">Quick-Start Guide</a><a class="headerlink" href="#quick-start-guide" title="Permalink to this headline">¶</a></h2>
<ol class="arabic simple">
<li><a class="reference internal" href="#docker-images"><span class="std std-ref">Running with Docker</span></a></li>
<li><a class="reference internal" href="#run-from-source"><span class="std std-ref">Install from Source</span></a></li>
</ol>
</div>
<div class="section" id="running-with-docker">
<span id="docker-images"></span><h2><a class="toc-backref" href="#id5">Running with Docker</a><a class="headerlink" href="#running-with-docker" title="Permalink to this headline">¶</a></h2>
<p>Docker images are offered on the <a class="reference external" href="https://hub.docker.com/r/elastichq/elasticsearch-hq/">ElasticHQ Dockerhub</a>.</p>
<p>Run with:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>docker run -p <span class="m">5000</span>:5000 elastichq/elasticsearch-hq
</pre></div>
</div>
<p>Access HQ with: <a class="reference external" href="http://localhost:5000">http://localhost:5000</a></p>
<p>When starting with Docker, see <a class="reference internal" href="#environment-variables"><span class="std std-ref">Environment Variables</span></a> for passing startup args. Environment variables are passed to docker using the <cite>-e</cite> flag.</p>
<p>ie. <code class="docutils literal"><span class="pre">-e</span> <span class="pre">HQ_DEFAULT_URL='http://aa.com:1212'</span></code></p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <code class="docutils literal"><span class="pre">latest</span></code> tag deploys the latest stable release. Where <code class="docutils literal"><span class="pre">develop</span></code> is the latest unstable working branch.</p>
</div>
</div>
<div class="section" id="install-from-source">
<span id="run-from-source"></span><h2><a class="toc-backref" href="#id6">Install from Source</a><a class="headerlink" href="#install-from-source" title="Permalink to this headline">¶</a></h2>
<div class="section" id="requirements">
<h3><a class="toc-backref" href="#id7">Requirements</a><a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>Python 3.4+</li>
<li>Elasticsearch. Supported versions: 2.x, 5.x, 6.x, 7.x</li>
</ul>
</div>
<div class="section" id="install-elastichq">
<h3><a class="toc-backref" href="#id8">Install ElasticHQ</a><a class="headerlink" href="#install-elastichq" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>Download or clone the repository <a class="reference external" href="https://github.com/ElasticHQ/elasticsearch-HQ">https://github.com/ElasticHQ/elasticsearch-HQ</a></li>
<li>Navigate to the root of the repository: <code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-r</span> <span class="pre">requirements.txt</span></code></li>
<li>Start the server: <code class="docutils literal"><span class="pre">python3</span> <span class="pre">application.py</span></code></li>
<li>Point your browser to: <a class="reference external" href="http://localhost:5000">http://localhost:5000</a></li>
</ol>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Alternatively, you can start the server with <code class="docutils literal"><span class="pre">python</span> <span class="pre">manage.py</span> <span class="pre">runserver</span></code></p>
</div>
</div>
<div class="section" id="pre-releases">
<h3><a class="toc-backref" href="#id9">Pre-Releases</a><a class="headerlink" href="#pre-releases" title="Permalink to this headline">¶</a></h3>
<p>Pre-release versions are made available as branches in the github repository. We use GitFlow methodology and adhere to semantic versioning.</p>
<p>Our branching organization is as follows:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">master</span></code>: contains Latest Stable release.</li>
<li><code class="docutils literal"><span class="pre">develop</span></code>: contains latest features. <strong>Not stable.</strong></li>
<li><code class="docutils literal"><span class="pre">#.#.#RC-#</span></code>: Release candidates are pre-release versions. <strong>Not stable.</strong></li>
</ul>
</div>
<div class="section" id="openshift">
<h3><a class="toc-backref" href="#id10">OpenShift</a><a class="headerlink" href="#openshift" title="Permalink to this headline">¶</a></h3>
<p>Information for running on openshift, can be found here: <a class="reference external" href="https://github.com/ElasticHQ/elasticsearch-HQ/blob/master/openshift/README.md">ElasticHQ OpenShift</a></p>
</div>
</div>
<div class="section" id="initial-login">
<h2><a class="toc-backref" href="#id11">Initial Login</a><a class="headerlink" href="#initial-login" title="Permalink to this headline">¶</a></h2>
<p>ElasticHQ is accessible, in default configuration under <a class="reference external" href="http://localhost:5000">http://localhost:5000</a></p>
<div class="figure align-center">
<a class="reference internal image-reference" href="_static/img/login.png"><img alt="_static/img/login.png" src="_static/img/login.png" style="width: 600px;" /></a>
</div>
<p>The input field takes a url in the form of: <code class="docutils literal"><span class="pre">http://DOMAIN:PORT</span></code></p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">http</span></code> or <code class="docutils literal"><span class="pre">https</span></code> are accepted schemes</li>
<li>For Basic Auth, use the format: <code class="docutils literal"><span class="pre">http://USERNAME:PASSWORD&#64;DOMAIN:PORT</span></code></li>
</ul>
</div>
<div class="section" id="configuration">
<h2><a class="toc-backref" href="#id12">Configuration</a><a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h2>
<div class="section" id="command-line-parameters">
<span id="id1"></span><h3><a class="toc-backref" href="#id13">Command line Parameters</a><a class="headerlink" href="#command-line-parameters" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal"><span class="pre">application.py</span></code> start script takes parameters passed in as arguments from the command line:</p>
<blockquote>
<div><table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="20%" />
<col width="65%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Arg</th>
<th class="head">Default Value</th>
<th class="head">Definition</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal"><span class="pre">--host</span></code></td>
<td>127.0.0.1</td>
<td>Host the HQ server should be reachable on.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">--port</span></code></td>
<td>5000</td>
<td>Port to reach HQ server.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">--debug</span></code></td>
<td>False</td>
<td>If True, exposes debug data to UI and causes reload on code changes.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">--url</span></code></td>
<td><code class="docutils literal"><span class="pre">http://localhost:9200</span></code></td>
<td>Default URL displayed on the initial connection screen.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">--enable-ssl</span></code></td>
<td>False</td>
<td>If flag is passed, assumes ssl cert will be used.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">--ca-certs</span></code></td>
<td>/path/to/your/ca.crt</td>
<td>Path to your CA Certificate. Required if enable-ssl is passed.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">--verify_certs</span></code></td>
<td>True</td>
<td>Whether HQ should attempt to validate certs. Set to False for self-signed certs.</td>
</tr>
</tbody>
</table>
</div></blockquote>
<div class="section" id="example">
<h4>Example:<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h4>
<div class="highlight-bash"><div class="highlight"><pre><span></span>python -m application
--enable-ssl
--ca-certs /path/to/your/ca.crt
</pre></div>
</div>
</div>
</div>
<div class="section" id="environment-variables">
<span id="id2"></span><h3><a class="toc-backref" href="#id14">Environment Variables</a><a class="headerlink" href="#environment-variables" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="20%" />
<col width="65%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Arg</th>
<th class="head">Default Value</th>
<th class="head">Definition</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal"><span class="pre">HQ_DEFAULT_URL</span></code></td>
<td><code class="docutils literal"><span class="pre">http://localhost:9200</span></code></td>
<td>Default URL displayed on the initial connection screen.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">HQ_ENABLE_SSL</span></code></td>
<td>False</td>
<td>If flag is passed, assumes ssl cert will be used.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">HQ_CA_CERTS</span></code></td>
<td>/path/to/your/ca.crt</td>
<td>Path to your CA Certificate. Required if enable-ssl is passed.</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">HQ_VERIFY_CERTS</span></code></td>
<td>True</td>
<td>Whether HQ should attempt to validate certs. Set to False for self-signed certs.</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">HQ_DEBUG</span></code></td>
<td>False</td>
<td>If True, enables debug level on logging.</td>
</tr>
</tbody>
</table>
</div></blockquote>
<div class="section" id="id3">
<h4>Example:<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
<div class="highlight-bash"><div class="highlight"><pre><span></span>docker run -p <span class="m">5000</span>:5000 elastichq/elasticsearch-hq
-e <span class="nv">HQ_DEFAULT_URL</span><span class="o">=</span><span class="s1">&#39;http://aa.com:1212&#39;</span>
-e <span class="nv">HQ_ENABLE_SSL</span><span class="o">=</span>False
</pre></div>
</div>
</div>
</div>
<div class="section" id="logging">
<h3><a class="toc-backref" href="#id15">Logging</a><a class="headerlink" href="#logging" title="Permalink to this headline">¶</a></h3>
<p>ElasticHQ logs out to console AND file by default. The application log file is located at the root of the HQ path and is called <code class="docutils literal"><span class="pre">application.log</span></code>.</p>
<p>Advanced users that want to have control over the logging output, can adjust it by altering the configuration file kept under <code class="docutils literal"><span class="pre">elastichq/config/logger.json</span></code>.</p>
<p>Docker users will find the logfile location under <code class="docutils literal"><span class="pre">/src/application.log</span></code></p>
</div>
<div class="section" id="connecting-with-ssl">
<h3><a class="toc-backref" href="#id16">Connecting with SSL</a><a class="headerlink" href="#connecting-with-ssl" title="Permalink to this headline">¶</a></h3>
<p>Thanks to a community contribution, SSL Cert support has been added: <a class="reference external" href="https://github.com/ElasticHQ/elasticsearch-HQ/issues/376">SSL Support</a>.</p>
<p>Enable SSL Cert support by starting HQ as so:</p>
<p><code class="docutils literal"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">application</span> <span class="pre">--enable-ssl</span> <span class="pre">--ca-certs</span> <span class="pre">/path/to/your/ca.crt</span></code></p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When using self-signed certs, you must disable certificate verification. See: <a class="reference internal" href="#command-line-parameters"><span class="std std-ref">Command line Parameters</span></a> or <a class="reference internal" href="#environment-variables"><span class="std std-ref">Environment Variables</span></a></p>
</div>
</div>
<div class="section" id="database">
<h3><a class="toc-backref" href="#id17">Database</a><a class="headerlink" href="#database" title="Permalink to this headline">¶</a></h3>
<p>ElasticHQ ships with SQLLite integration to store clusters you have connected to and other meta information. This database is kept under the root directory as <code class="docutils literal"><span class="pre">elastichq.db</span></code>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In the event you want to start with a clean slate, simply delete the <code class="docutils literal"><span class="pre">elastichq.db</span></code> file. ElasticHQ will recreate it at next startup.</p>
</div>
</div>
<div class="section" id="external-configuration">
<h3><a class="toc-backref" href="#id18">External Configuration</a><a class="headerlink" href="#external-configuration" title="Permalink to this headline">¶</a></h3>
<p>External configuration files are supported for those wanting to preserve their user-specified settings between upgrades.</p>
<p>On startup, HQ checks the following locations for a file named <code class="docutils literal"><span class="pre">settings.json</span></code>:</p>
<ul class="simple">
<li><cite>/etc/elastic-hq/settings.json</cite></li>
<li><cite>~/settings.json</cite></li>
<li>CURRENT WORKING DIRECTORY + <code class="docutils literal"><span class="pre">/settings.json</span></code></li>
<li>CURRENT WORKING DIRECTORY + <code class="docutils literal"><span class="pre">/elastichq/settings.json</span></code></li>
<li>CURRENT WORKING DIRECTORY + <code class="docutils literal"><span class="pre">/config/settings.json</span></code></li>
</ul>
<p>Current supported parameters are:</p>
<blockquote>
<div><table border="1" class="docutils">
<colgroup>
<col width="28%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Key</th>
<th class="head">Definition</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal"><span class="pre">SQLALCHEMY_DATABASE_URI</span></code></td>
<td>Location and Name of ElasticHQ database file.</td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>The settings file should be in standard JSON:</p>
<div class="highlight-json"><div class="highlight"><pre><span></span><span class="p">{</span>
  <span class="nt">&quot;SQLALCHEMY_DATABASE_URI&quot;</span> <span class="p">:</span>  <span class="s2">&quot;sqlite:////SOME/PATH/TO/DB_NAME.db&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="upgrading">
<h2><a class="toc-backref" href="#id19">Upgrading</a><a class="headerlink" href="#upgrading" title="Permalink to this headline">¶</a></h2>
<p>We adhere to semantic versioning, so as long as the Major version hasn&#8217;t changed, you can expect everything to work well enough. ;-)</p>
<div class="section" id="latest-version">
<h3><a class="toc-backref" href="#id20">Latest Version</a><a class="headerlink" href="#latest-version" title="Permalink to this headline">¶</a></h3>
<p>ElasticHQ checks against the Elastichq.org website, to retrieve the latest stable version number. You can see the check in the footer:</p>
<p><strong>Versions Match:</strong></p>
<div class="figure align-center">
<a class="reference internal image-reference" href="_static/img/footer_version_1.png"><img alt="_static/img/footer_version_1.png" src="_static/img/footer_version_1.png" style="width: 600px;" /></a>
</div>
<p><strong>Time to Upgrade:</strong></p>
<div class="figure align-center">
<a class="reference internal image-reference" href="_static/img/footer_version_2.png"><img alt="_static/img/footer_version_2.png" src="_static/img/footer_version_2.png" style="width: 600px;" /></a>
</div>
</div>
<div class="section" id="upgrading-minor-and-patch-versions">
<h3><a class="toc-backref" href="#id21">Upgrading Minor and Patch versions</a><a class="headerlink" href="#upgrading-minor-and-patch-versions" title="Permalink to this headline">¶</a></h3>
<ol class="arabic simple">
<li>To upgrade, simply download or clone the repository master branch.</li>
<li>Upgrade the database: <code class="docutils literal"><span class="pre">python</span> <span class="pre">manage.py</span> <span class="pre">db</span> <span class="pre">upgrade</span></code></li>
<li>(Re)Start the server: <code class="docutils literal"><span class="pre">python</span> <span class="pre">application.py</span></code></li>
<li>Point your browser to: <a class="reference external" href="http://localhost:5000">http://localhost:5000</a></li>
</ol>
</div>
</div>
<div class="section" id="running-in-production">
<h2><a class="toc-backref" href="#id22">Running in Production</a><a class="headerlink" href="#running-in-production" title="Permalink to this headline">¶</a></h2>
<p>We advise that under any considerable usage/load, this application should be run with a multithreaded server. The current flask implementation by itself should not be run in production without this, as it is a single-threaded process.</p>
<p>We recommend running this WSGI application with gunicorn. The Docker container available on DockerHub is pre-configured to run with gunicorn, and is preferred. See the <a class="reference internal" href="#docker-images"><span class="std std-ref">Running with Docker</span></a></p>
<p>If you wish to run without a container, install gunicorn by either commenting out the line in the <code class="docutils literal"><span class="pre">requirements.txt</span></code> file or simply running <code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">gunicorn</span></code></p>
<p>In console, run gunicorn with:</p>
<p><code class="docutils literal"><span class="pre">gunicorn</span> <span class="pre">-w</span> <span class="pre">1</span> <span class="pre">-b</span> <span class="pre">:5000</span> <span class="pre">--worker-class</span> <span class="pre">eventlet</span> <span class="pre">application:application</span></code></p>
<p>The application will be accessible under <a class="reference external" href="http://127.0.0.1:5000">http://127.0.0.1:5000</a></p>
<p>Read the <a class="reference external" href="http://docs.gunicorn.org/en/stable/configure.html">Gunicorn Docs</a> for further command line options.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For the <em>Metrics</em> section to broadcast via websocket, you must have gunicorn set to 1 worker.</p>
</div>
</div>
<div class="section" id="troubleshooting">
<h2><a class="toc-backref" href="#id23">Troubleshooting</a><a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h2>
<div class="section" id="diagnosing-connection-errors">
<h3><a class="toc-backref" href="#id24">Diagnosing connection errors</a><a class="headerlink" href="#diagnosing-connection-errors" title="Permalink to this headline">¶</a></h3>
<p>Failure in connecting initially to an Elasticsearch cluster, can happen for several reason:</p>
<ul class="simple">
<li><strong>Basic Authentication:</strong> If you did not enter in the security credentials in the connection URL, HQ will fail to connect. The proper format is <code class="docutils literal"><span class="pre">http://USERNAME:PASSWORD&#64;DOMAIN:PORT</span></code></li>
<li><strong>X-Pack License Expiration:</strong> X-Pack comes with a #-day license that will silently expire. Expiration of the license may cause connectivity issues, so it is advised to either purchase an X-Pack license or uninstall X-Pack.</li>
<li><strong>No Route to ES cluster:</strong> Confirm that the server running HQ has access to ES via network. You can do this by calling ES from within a terminal window on the HQ server, with a <code class="docutils literal"><span class="pre">curl</span> <span class="pre">-XGET</span> <span class="pre">http://DOMAIN:PORT</span></code>.</li>
<li><strong>CERTIFICATE_VERIFY_FAILED:</strong> If you see this error in the log, you are most likely using a self-signed cert and did not set validate_certs variable to false. See: <a class="reference internal" href="#command-line-parameters"><span class="std std-ref">Command line Parameters</span></a> or <a class="reference internal" href="#environment-variables"><span class="std std-ref">Environment Variables</span></a></li>
</ul>
</div>
<div class="section" id="x-pack-integration">
<span id="xpack-integration"></span><h3><a class="toc-backref" href="#id25">X-Pack Integration</a><a class="headerlink" href="#x-pack-integration" title="Permalink to this headline">¶</a></h3>
<p>X-Pack is configured with authentication. To connect, you must pass along the username and password in the connection URL
using the format <code class="docutils literal"><span class="pre">http://USERNAME:PASSWORD&#64;DOMAIN:PORT</span></code></p>
<p>ElasticHQ will store the username and password in the database, so future connectivity is not an issue.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">We do realize that the username and passwords are stored plain text in the ElasticHQ DB, but this is a necessary evil that allows for easy reconnection.</p>
</div>
</div>
<div class="section" id="viewing-logs">
<h3><a class="toc-backref" href="#id26">Viewing Logs</a><a class="headerlink" href="#viewing-logs" title="Permalink to this headline">¶</a></h3>
<p>In the base installation, the logs are available under the <code class="docutils literal"><span class="pre">/install/path/application.log</span></code>.</p>
<p>For docker images, the application logging can be found under <code class="docutils literal"><span class="pre">/src/application.log</span></code>.</p>
</div>
<div class="section" id="ssl-cert-not-working">
<span id="ssl-trouble"></span><h3><a class="toc-backref" href="#id27">SSL Cert not working</a><a class="headerlink" href="#ssl-cert-not-working" title="Permalink to this headline">¶</a></h3>
<p><strong>NOTE: Your CA file must be the same signer of your Elasticsearch node, for HQ to connect as a trusted source.</strong></p>
<p>Verify that the certificate works by connecting directly from the HQ instance to the ES node in question, using the cert:</p>
<p><code class="docutils literal"><span class="pre">curl</span> <span class="pre">-u</span> <span class="pre">admin:password</span> <span class="pre">--ca-certs</span> <span class="pre">/path/to/ca.crt</span> <span class="pre">https://localhost:9200/_cluster/settings?pretty</span></code></p>
</div>
<div class="section" id="preserving-database-across-docker-container-restarts">
<h3><a class="toc-backref" href="#id28">Preserving Database across Docker container restarts</a><a class="headerlink" href="#preserving-database-across-docker-container-restarts" title="Permalink to this headline">¶</a></h3>
<p>The following code block originated as an issue (<a class="reference external" href="https://github.com/ElasticHQ/elasticsearch-HQ/issues/409">https://github.com/ElasticHQ/elasticsearch-HQ/issues/409</a>) for those wanting to preserve the HQ SQLLite DB between container restarts.</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>docker run --detach
--restart<span class="o">=</span>always
--net host
--volume elastichq:/src/db
--name elastichq
elastichq/elasticsearch-hq
sh -x -c <span class="s1">&#39;sed -i -r -e &quot;s/_sqlalchemy_database_uri =.*/_sqlalchemy_database_uri = &quot;sqlite:///&quot; + os.path.join(BASEPATH, &quot;db&quot; , &quot;elastichq.db&quot;)/&quot; /src/elastichq/config/settings.py &amp;&amp; exec supervisord -c /etc/supervisor/supervisord.conf&#39;</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="license">
<h2><a class="toc-backref" href="#id29">License</a><a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h2>
<p>Copyright 2013-2018 Roy Russo and Authors</p>
<p>Licensed under the Apache License, Version 2.0 (the &#8220;License&#8221;);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</p>
<blockquote>
<div><a class="reference external" href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a></div></blockquote>
<p>Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an &#8220;AS IS&#8221; BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.</p>
</div>
</div>


          </div>
            
  <div class="footer-relations">
    
      <div class="pull-left">
        <a class="btn btn-default" href="index.html" title="previous chapter (use the left arrow)">ElasticHQ Documentation</a>
      </div>
    
      <div class="pull-right">
        <a class="btn btn-default" href="rest-api.html" title="next chapter (use the right arrow)">REST API</a>
      </div>
    </div>
    <div class="clearer"></div>
  
        </div>
        <div class="clearfix"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="http-routingtable.html" title="HTTP Routing Table"
             >routing table</a> |</li>
        <li class="right" >
          <a href="rest-api.html" title="REST API"
             >next</a> |</li>
        <li class="right" >
          <a href="index.html" title="ElasticHQ Documentation"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">ElasticHQ latest documentation</a> &#187;</li> 
      </ul>
    </div>
<script type="text/javascript">
  $("#mobile-toggle a").click(function () {
    $("#left-column").toggle();
  });
</script>
<script type="text/javascript" src="_static/js/bootstrap.js"></script>
  <div class="footer">
    &copy; Copyright 2018, ElasticHQ. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
  </div>
    <script type="text/javascript">
      var _gaq = _gaq || [];
      _gaq.push(['_setAccount', 'UA-40876494-1']);
      _gaq.push(['_trackPageview']);
      (function() {
        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
      })();
    </script>
  </body>
</html>